feat(earn): add geo-blocking for mUSD conversion feature by nickewansmith · Pull Request #24501 · MetaMask/metamask-mobile

nickewansmith · 2026-01-13T21:59:22Z

Description

What is the reason for the change?

As MetaMask Legal, we need to geofence the mUSD conversion feature so it is not available in countries where it is not compliant. This ensures regulatory compliance by restricting access to the convert feature in specific regions.

What is the improvement/solution?

This PR implements geo-blocking for the mUSD conversion feature using a two-tier approach:

LaunchDarkly (Primary): Remote feature flag earnMusdConversionGeoBlockedCountries with { blockedCountries: ["GB", ...] } structure
Environment Variable (Fallback): MM_MUSD_CONVERSION_GEO_BLOCKED_COUNTRIES as comma-separated country codes (e.g., "GB,US")
The implementation leverages the existing RampsController geolocation data and integrates geo-blocking checks everywhere the mUSD conversion flow is enabled.
Key changes:
New selectMusdConversionBlockedCountries selector with LD + env var fallback
New useMusdConversionEligibility hook combining geolocation with blocked countries
Geo-blocking integrated into: useMusdCtaVisibility, EarnBalance, EarnLendingBalance, TokenListItem, and useCustomAmount

Changelog

CHANGELOG entry: Added geo-blocking for mUSD conversion feature to restrict access in non-compliant countries

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/MUSD-194

Manual testing steps

Feature: mUSD Conversion Geo-blocking

  Scenario: UK user cannot see mUSD conversion CTA
    Given user is located in the UK (GB)
    And user has a convertible stablecoin (USDC, DAI, USDT)
    And MM_MUSD_CONVERSION_GEO_BLOCKED_COUNTRIES="GB" or LD flag blocks GB

    When user views their token list
    Then user does not see "Convert to mUSD" CTA
    And user cannot access the mUSD conversion flow

  Scenario: US user can see mUSD conversion CTA
    Given user is located in the US
    And user has a convertible stablecoin (USDC, DAI, USDT)
    And GB is the only blocked country

    When user views their token list
    Then user sees "Convert to mUSD" CTA
    And user can initiate the mUSD conversion flow

  Scenario: Fallback to env var when LaunchDarkly unavailable
    Given LaunchDarkly flag earnMusdConversionGeoBlockedCountries is not configured
    And MM_MUSD_CONVERSION_GEO_BLOCKED_COUNTRIES="GB" is set

    When selector evaluates blocked countries
    Then GB is returned as a blocked country

Screenshots/Recordings

Before

n/a

After

n/a

Pre-merge author checklist

I’ve followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
I've completed the PR template to the best of my ability
I’ve included tests if applicable
I’ve documented my code using JSDoc format if applicable
I’ve applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

Note

Implements geofencing for the mUSD conversion experience across Earn surfaces, driven by remote config with a local fallback.

Adds selectMusdConversionBlockedCountries (LD earnMusdConversionGeoBlockedCountries → { blockedRegions: string[] }) with env fallback MM_MUSD_CONVERSION_GEO_BLOCKED_COUNTRIES and parseBlockedCountriesEnv; defaults to ['GB'] via DEFAULT_MUSD_BLOCKED_COUNTRIES
Introduces useMusdConversionEligibility (uses getDetectedGeolocation; blocks by default when undefined) returning isEligible, isLoading, geolocation, blockedCountries
Gates UI/flows by geo-eligibility: useMusdCtaVisibility (Buy/Get, token-list-item, asset-overview CTAs), EarnBalance (requires isGeoEligible for isConvertibleStablecoin), EarnLendingBalance (asset overview CTA), TokenListItem and Tokens (list CTA), useCustomAmount (mUSD tag)
Updates .js.env.example with MM_MUSD_CONVERSION_GEO_BLOCKED_COUNTRIES and adds constants in musd.ts
Extensive unit tests added/updated to cover geo-eligible/blocked paths across hooks and components

^{Written by Cursor Bugbot for commit 96cb7be. This will update automatically on new commits. Configure here.}

github-actions · 2026-01-13T21:59:32Z

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

bergarces

Ok from Assets

Let us know when the conflicts are resolved and we'll re-approve.

Matt561

Pre-approving so you're not blocked. We should double-check if we want to block or allow by default.

…e-to-geofence-the-convert-feature-so-that-it-is-not-available-in-countries-where-it-is-not-compliant

github-actions · 2026-01-20T22:44:56Z

🔍 Smart E2E Test Selection

Selected E2E tags: None (no tests recommended)
Risk Level: low
AI Confidence: 85%

click to see 🤖 AI reasoning details

This PR adds geo-blocking functionality for the mUSD conversion feature within the Earn module. The changes are:

Highly scoped: All changes are contained within the Earn/mUSD feature components and hooks
Feature-flagged: The mUSD conversion feature is controlled by remote feature flags (selectIsMusdConversionFlowEnabledFlag)
No E2E test coverage exists: Grep search confirmed no E2E tests exist for "musd", "mUSD", "MUSD", or "Earn" in the e2e directory
Well unit-tested: The PR includes comprehensive unit tests for all new functionality (useMusdConversionEligibility, selectMusdConversionBlockedCountries, parseBlockedCountriesEnv)
Additive changes: The geo-blocking adds an additional check (isGeoEligible) to existing conditions - it doesn't modify core logic
No impact on core flows: The changes don't affect wallet creation, account management, network switching, confirmations, or any other core functionality

The changes affect:

EarnBalance component (adds geo-eligibility check)
Tokens component (adds geo-eligibility check for mUSD CTA)
useMusdCtaVisibility hook (adds geo-blocking checks)
useCustomAmount hook (adds geo-eligibility check for mUSD conversion transactions)

Since there are no E2E tests for the Earn/mUSD feature, and the changes are purely additive geo-blocking logic that doesn't affect any existing E2E test flows, no E2E tags need to be run.

View GitHub Actions results

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

cursor · 2026-01-20T22:48:24Z

+        showNetworkIcon: false,
+        selectedChainId: null,
+      };
+    }


Missing isEmptyWallet in geo-blocked return path

Medium Severity

The shouldShowBuyGetMusdCta function's return object when the user is geo-blocked is missing the isEmptyWallet property that all other return paths include. The function's documented return type and consumer code (MusdConversionAssetListCta) expect isEmptyWallet to always be present. While the current component early-returns when shouldShowCta is false (preventing immediate runtime issues), this inconsistency breaks the function's contract, causes type inference issues, and could lead to bugs if consuming code is refactored.

This won't break anything, I'll address it in another PR.

sonarqubecloud · 2026-01-20T23:07:05Z

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

metamaskbot added the team-earn label Jan 13, 2026

nickewansmith marked this pull request as ready for review January 13, 2026 21:59

nickewansmith requested review from a team as code owners January 13, 2026 21:59

github-actions Bot added the size-L label Jan 13, 2026

cursor Bot reviewed Jan 13, 2026

View reviewed changes

Comment thread app/components/UI/Earn/selectors/featureFlags/index.ts

cursor Bot reviewed Jan 14, 2026

View reviewed changes

Comment thread app/components/UI/Earn/selectors/featureFlags/index.ts

nickewansmith force-pushed the MUSD-194-as-meta-mask-legal-i-want-to-be-able-to-geofence-the-convert-feature-so-that-it-is-not-available-in-countries-where-it-is-not-compliant branch 2 times, most recently from c7b8d6b to 5daf61a Compare January 14, 2026 16:30

bergarces previously approved these changes Jan 15, 2026

View reviewed changes

nickewansmith added 2 commits January 15, 2026 06:53

feat(earn): add geo-blocking for mUSD conversion feature

793073a

fix: test unit update to blockRegion for feature flag object

e9d1bbd

nickewansmith dismissed bergarces’s stale review via e9d1bbd January 15, 2026 13:01

nickewansmith force-pushed the MUSD-194-as-meta-mask-legal-i-want-to-be-able-to-geofence-the-convert-feature-so-that-it-is-not-available-in-countries-where-it-is-not-compliant branch from 5daf61a to e9d1bbd Compare January 15, 2026 13:01

nickewansmith requested a review from bergarces January 15, 2026 13:01

github-actions Bot added size-XL and removed size-L labels Jan 15, 2026

Matt561 previously approved these changes Jan 15, 2026

View reviewed changes

Comment thread app/components/UI/Earn/hooks/useMusdConversionEligibility.ts Outdated

nickewansmith added 3 commits January 15, 2026 11:57

chore: resolve conflict main

92a8ceb

fix: unit test tsc

81c7228

chore: address feedback, default to GB blocked, resolve conflict

99b4a75

nickewansmith dismissed Matt561’s stale review via 99b4a75 January 15, 2026 18:07

nickewansmith force-pushed the MUSD-194-as-meta-mask-legal-i-want-to-be-able-to-geofence-the-convert-feature-so-that-it-is-not-available-in-countries-where-it-is-not-compliant branch from 426125b to 99b4a75 Compare January 15, 2026 18:07

nickewansmith requested a review from Matt561 January 15, 2026 18:08

cursor Bot reviewed Jan 15, 2026

View reviewed changes

Comment thread app/components/UI/Earn/hooks/useMusdConversionEligibility.ts

nickewansmith added 3 commits January 15, 2026 12:47

fix: eslint

ae60a5a

chore: merge main resolve conflict

a2a6ddb

chore: address bugbot feedback

041502b

cursor Bot reviewed Jan 15, 2026

View reviewed changes

Comment thread app/components/UI/Earn/selectors/featureFlags/index.ts

Merge branch 'main' into MUSD-194-as-meta-mask-legal-i-want-to-be-abl…

35cbe7c

…e-to-geofence-the-convert-feature-so-that-it-is-not-available-in-countries-where-it-is-not-compliant

cursor Bot reviewed Jan 15, 2026

View reviewed changes

Comment thread app/components/UI/Earn/components/EarnBalance/EarnBalance.test.tsx

nickewansmith added 3 commits January 15, 2026 14:37

Merge branch 'main' into MUSD-194-as-meta-mask-legal-i-want-to-be-abl…

f3862a1

…e-to-geofence-the-convert-feature-so-that-it-is-not-available-in-countries-where-it-is-not-compliant

chore: merge main resolve conflict

bd1dca5

chore: fix tests after merge conflict

c2a5d80

Matt561 previously approved these changes Jan 20, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

nickewansmith added 2 commits January 20, 2026 13:43

chore: merge main resolve conflict

8778dc2

chore: update unit tests for removal of ramps selector

8c46a7e

nickewansmith dismissed Matt561’s stale review via 8c46a7e January 20, 2026 20:30

This comment was marked as outdated.

Sign in to view

nickewansmith requested a review from Matt561 January 20, 2026 20:48

Matt561 previously approved these changes Jan 20, 2026

View reviewed changes

chore: update tests bugbot comment

14803fa

nickewansmith dismissed Matt561’s stale review via 14803fa January 20, 2026 22:29

nickewansmith added 2 commits January 20, 2026 16:37

chore: merge main resolve conflict

a77c6c8

chore: fix bad merge resolution update test

96cb7be

cursor Bot reviewed Jan 20, 2026

View reviewed changes

nickewansmith requested a review from Matt561 January 20, 2026 23:39

Matt561 approved these changes Jan 20, 2026

View reviewed changes

Prithpal-Sooriya approved these changes Jan 21, 2026

View reviewed changes

nickewansmith added this pull request to the merge queue Jan 21, 2026

Merged via the queue into main with commit a7809e8 Jan 21, 2026
59 of 60 checks passed

nickewansmith deleted the MUSD-194-as-meta-mask-legal-i-want-to-be-able-to-geofence-the-convert-feature-so-that-it-is-not-available-in-countries-where-it-is-not-compliant branch January 21, 2026 02:35

github-actions Bot locked and limited conversation to collaborators Jan 21, 2026

metamaskbot added the release-7.63.0 Issue or pull request that will be included in release 7.63.0 label Jan 21, 2026

Uh oh!

Conversation

nickewansmith commented Jan 13, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What is the reason for the change?

What is the improvement/solution?

Changelog

Related issues

Manual testing steps

Screenshots/Recordings

Before

After

Pre-merge author checklist

Pre-merge reviewer checklist

Uh oh!

github-actions Bot commented Jan 13, 2026

Uh oh!

Uh oh!

Uh oh!

bergarces left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Matt561 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions Bot commented Jan 20, 2026

🔍 Smart E2E Test Selection

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jan 20, 2026

Choose a reason for hiding this comment

Missing isEmptyWallet in geo-blocked return path

Uh oh!

nickewansmith Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Jan 20, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nickewansmith commented Jan 13, 2026 •

edited by cursor Bot

Loading

bergarces left a comment •

edited

Loading

Missing `isEmptyWallet` in geo-blocked return path